Skip to content

csnode: snapshots served by the node over HTTP - #98

Draft
EnzinoBB wants to merge 9 commits into
masterfrom
feat/snapshot-server
Draft

EnzinoBB wants to merge 9 commits into
masterfrom
feat/snapshot-server

Conversation

@EnzinoBB

Copy link
Copy Markdown
Collaborator

Step 4 of snapshots served by community nodes (plan on docs/snapshot-serving).

  • SnapshotServer (Boost.Beast, header-only, no new dependency): GET and HEAD of /snapshot/latest.json and /snapshot/<seq>/<name>, with these limits:

    • one Range of at most 16 MiB;
    • 8 KB of headers;
    • 15 s idle and 30 s write timeouts;
    • at most serve_max_connections (503 beyond);
    • a bandwidth cap shared by all connections (serve_rate_kbps, KB/s).

    Only file names of the loaded manifest are served, never a path from the request.

  • Only synced nodes serve (user's rule): 503 with Retry-After while the node is more than 3 rounds behind the current round or has no snapshot built. latest.json carries synced_to, the node's last block, outside the signed line.

  • SnapshotService, owned by Node: every 10 s it reads [snapshot] and starts, stops (port 0) or moves the server, applying the limits while it runs, with no restart. While serving, it builds the snapshot of each new periodic checkpoint, and of the latest one at start, at low priority into snapshot/, and serves it once complete.

  • The builder reads checkpoint files in 4 MiB pieces (Fable's note: it now runs inside the node).

Off by default (serve_port=0).

Tests: a real server on a free port with a Beast client: manifest, whole file, ranges (first bytes, suffix, open end), HEAD, 416 (beyond the end, two ranges), 404 (other block, traversal, private file, root), 405, 503 when not synced or nothing built, the connection cap, the rate cap (300 KB at 100 KB/s), moving to another port and stopping. The dynamic start on a live network is step 7's scenarios.

🤖 Generated with Claude Code

EnzinoBB and others added 9 commits October 25, 2026 07:50
A node with [snapshot] serve_port set serves the snapshots it builds:
- SnapshotServer (Boost.Beast, header-only): GET and HEAD of
  /snapshot/latest.json and /snapshot/<seq>/<name>, one Range of at most
  16 MiB, 8 KB of headers, 15 s idle and 30 s write timeouts, at most
  serve_max_connections (503 beyond), a bandwidth cap shared by all
  connections (serve_rate_kbps, kilobytes a second); only names of the
  loaded manifest are served, never a path from the request. It answers
  503 while the node is more than 3 rounds behind the network or has no
  snapshot built: only synced nodes serve. latest.json carries the
  node's last block (synced_to, outside the signed line).
- SnapshotService, owned by Node: every 10 s it reads [snapshot] and
  starts, stops (port 0) or moves the server, applying the limits while
  it runs; while serving it builds the snapshot of each new periodic
  checkpoint (checkpointSavedEvent) and of the latest one when it starts,
  at low priority, into snapshot/, and serves it once complete.
- The builder reads checkpoint files in 4 MiB pieces; Storage and
  BlockChain give the contract records to it.

Off by default (serve_port=0). Step 4 of snapshots served by community
nodes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A session keeps the server's state alive (shared ownership) and the
  bandwidth wait gives up when the server stops; stopping waits for every
  session to end, so nothing outlives what it uses.
- Every request's headers must arrive within 10 s and a body must flow at
  32 KB/s at least (more time under the bandwidth cap): the accept thread
  closes connections past their deadline, so a client sending byte by
  byte holds no slot. At most 2 connections per address.
- Node-built snapshots carry no contract records: the contracts database
  holds each contract's latest state, later than the checkpoint, while
  the signed snapshot is the state at the checkpoint, which carries the
  contract states at its block; a node fetches any it lacks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…g write deadline

- Expired connections are closed on every pass of the accept loop, also
  while connections keep arriving.
- The per-address cap counts IPv4 addresses (IPv4-mapped ones too) and
  IPv6 /64 networks.
- Every piece written renews a 30 s deadline, instead of one deadline
  for the whole body: a reader that stops reading is closed within it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…time

A reader whose average rate, over the time spent writing to it (the
bandwidth cap's waits not counted), falls below 32 KB/s after 10 s of
writing is dropped; a connection takes no new request after 30 minutes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…quest

The minimum average rate and the 30-minute limit are counted across all
requests of a connection, and the limit also ends a body being written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…serve)

SNAPSHOT_SERVE_NODE gives that node [snapshot] serve_port; at the end it
must have built the snapshot of a periodic checkpoint and serve it: the
manifest is fetched, the first piece of the blocks file has the declared
hash, and a path outside the snapshot is answered 404.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- The bandwidth cap lets a piece larger than a second's worth through
  once the bucket is out of debt (a cap below 65 KB/s hung every body),
  and its wait ends with the connection's time; the write deadline starts
  after that wait. The bucket starts empty when the rate is set.
- A node that has not heard the network (round 0) is not synced.
- Without serve_bind, a host without IPv6 listens on every IPv4
  interface; a listen failure is logged once per setting.
- The build starts above the blocks pruning is removing, reads stored
  bytes directly (no parsing, no pool cache), checks the free disk, is
  tried again a minute later up to 5 times, and stops between pieces of a
  checkpoint file.
- HEAD error replies carry no body; the settings are copied, not held.
- Tests: round 0 answers 503; a 50 KB/s cap completes a 100 KB range.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@EnzinoBB

Copy link
Copy Markdown
Collaborator Author

Put aside: the user decided to move snapshots over the node's p2p layer (state served by community neighbours, blocks via backward sync), so the node does not need an HTTP server. The builder service may be reused by the new plan; this PR stays open as a reference until the plan says what survives.

EnzinoBB added a commit that referenced this pull request Oct 25, 2026
SnapshotProvider answers manifest and piece requests from the newest snapshot
this node built: verified on load, files kept open, pieces read with pread,
a global and a per-peer token bucket, two pieces per peer every 100 ms, at
most serve_max_peers peers in 30 s, half the budget while trusted, manifests
once per peer every 5 s. SnapshotService (from #98, without the HTTP server)
builds the snapshot of each periodic checkpoint while serve is on and loads it
into the provider. Snapshots use 512 KiB chunks and no contracts file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant